\input texinfo @c -*- Mode: Texinfo -*- 
@c readme-e.tex -- readme file for the TeX and Metafont executables
@c Author          : Frank Ridderbusch
@c Created On      : Tue Jan 15 19:35:42 1991
@c Last Modified By: Frank Ridderbusch
@c Last Modified On: Fri Jul 19 21:53:06 1991
@c Update Count    : 19
@c Status          : Release
@c 
@c HISTORY 
@c 19-Jul-1991		Frank Ridderbusch	
@c    Last Modified: Fri Jul 19 11:23:56 1991 #17 (Frank Ridderbusch T35)
@c    Fixing some types (Thanks, Ralf Sobek) inclusion of current
@c    configuration values.
@c 19-Jul-1991		Frank Ridderbusch T35	
@c    Last Modified: Tue Jul 16 13:49:00 1991 #12 (Frank Ridderbusch T35)
@c    Bring this file up to date with my most recent changes concerning
@c    tex-conf.ttp and BigTeX and linking with the MiNT library.
@c  2-Mar-1991		Frank Ridderbusch	
@c    Decription of dynamic memory allocation.
@c 31-Jan-1991		Frank Ridderbusch	
@c    Modification to reflect cleanup of my modification to the files in
@c    the common directory.
@c 15-Jan-1991		Frank Ridderbusch	
@c    First version for the executables, as been send to David Megginson
@c    and which later appeared on terminator.
@c
@c %**start of header
@setfilename readme-e.inf
@settitle readme-e
@c %**end of header

@ifinfo
This file documents a @TeX{} 3.1 and METAFONT 2.7 implementation for the
Atari ST based on the WEB2C kit 5.8a from Karl Berry.

Copyright (C) 1990,1991 Frank Ridderbusch

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@titlepage
@title @TeX{} 3.1 and METAFONT 2.7 for the Atari ST
@subtitle README for the Executables
@subtitle @today
@author by Frank Ridderbusch

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990,1991 Frank Ridderbusch

Permission is granted to make and distribute verbatim copies of this
description provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
description under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage


@unnumberedsec Preface

If you have already read earlier versions of this readme file, you can
directly turn to the section "Dynamic memory allocation".

There is one important modification, I made, that I would like to
mention just at the beginning. There are @strong{no} files
@file{initex.ttp} or @file{inimf.ttp} any longer, as there have been in
earlier versions. I have merged the functions which are unique to
@file{initex.ttp} or @file{inimf.ttp} into one executable (no big deal,
only changing some defines). Therefore only the files @file{tex.ttp} and
@file{mf.ttp} are in the archive. The specific @samp{initex} or
@samp{inimf} functions (dumping) are selected by a commandline option.
(See section @samp{Installation and Usage})

@unnumberedsec General Remarks

This archive contains executables for the Atari ST. All executables
were generated from the WEB and the WEB2C sources version 5.8a, which
Karl Berry announced and released in a TeXhax digest, which appeared
on my news site during November 1990.

The Atari executables were first compiled with the GNU C compiler
v1.37.1 running in an Un*x cross-compiling environment. The resulting
objects were then linked with the C-library (at patchlevel 58), which
J.R.Bammi and E.R.Smith put together (Thanks to both of them for their
good work). Later, after some additional minor changes, I recompiled the
C sources with GCC v1.38 and maximum optimization at home on my ST,
which is equipped with 2,5 meg. After obtaining GCC v1.40, the final
recompilation took place with this version. The executables are
currently linked with the library (version 8) from E.R.Smith, which he
build for MiNT, his multitasking TOS extension. Additionally the archive
contains a Big@TeX{} version with very large buffers (for those of you,
who have a Mega 4 ST and use very large macro packages).

If you don't have a cross compiling environment and want to recompile
the sources, you can just as well convert the WEB sources to C on your
local Un*x box and then carry the C sources home. If you want to do
this, it a good idea to decrease the constant @code{MAXLINES} to
@samp{1000} in the file @file{src-5.8a/web2c/splitup.c}. After that, you
should be able to compile all files.@refill

@unnumberedsec Implementation Details

The files from the WEB2C kit required only very minor changes, mostly
things concerning the slash as a path separator opposed to the backslash
the Atari uses. @TeX{} and METAFONT both discard any @samp{\r} (Carriage
Return) character before a @samp{\n} (Newline) in the input of normal
tex files (The everlasting difference between Un*x and other systems;
@samp{\n} versus @samp{\r\n} as line separators). I also modified the
programs @file{pltopf} and @file{vptovf} to ignore any @samp{\r}
characters. If you encounter any problems with error messages about
illegal character in the input file, try at first to remove any
@samp{\r} characters before you investigate further. It should be
trivial to write a small utility, which removes all @samp{\r} characters
from an input file.@refill

@TeX{} and METAFONT both passed the trip and the trap tests on the Atari.

METAFONT doesn't have any window support on the ST. (If someone would
write a window interface for the ST, I would be very interested.) I
don't mean a GEM interface with this remark. METAFONT has a
rudimentary window interface, to display proof mode character on
screen. The WEB2C kit provides support for X11, X10 and some others.

All executables will open any file in binary mode.

@unnumberedsec Installation and Usage

The complete @TeX{} and METAFONT environment is controlled via
environment variables ala Un*x. On my Atari I've set the following
values (as an example under gulam):

@example
# All TeX font metric files are here.
setenv TEXFONTS f:\tex\texinput\tfm
# The dumped format files are found here.
setenv TEXFORMATS f:\tex\formats
# search paths for TeX input files
setenv TEXINPUTS .;f:\tex\texinput\latex\styles;f:\tex\texinput\macros
# The TeX string pool file is found here.
setenv TEXPOOL f:\tex
# The Metafont string pool file is found here.
setenv MFPOOL f:\metafont\mfbases
# The dumped base file is found here.
setenv MFBASES f:\metafont\mfbases
# search paths for Metafont input files
setenv MFINPUTS .;f:\metafont\mfinputs\cmr
@end example

(For a detailed description the above environment variables see the
manual pages in the file @file{manpages.lzh}, also available from the atari
archive at terminator.)

The executables don't care about slashes or backslashes as
path separators. Both can be used. Don't mind, that the string pool files
are called @file{*.poo} instead of @file{*.pool'}. The executables have
no problems to find them.@refill

The @samp{initex} or @samp{inimf} specific functions (dumping) are
selected by giving the option @code{-i} as the last argument. Therefore
to create the @file{plain.fmt} you have to issue the following
commandline (assuming the environment variables are set
correctly):@refill 

@example
tex 'plain \dump' -i
@end example

The same applies to METAFONT. As a sidenote, the @file{plain.fmt} file
from the Big@TeX{} is about 110 KB larger than the one from the normal
@TeX{}, which is about 168 KB in size. The absolute sizes vary
depending on the sizes of the internal buffers.@refill

Also the utility programs may search along some path for some files set
by an environment variable. So, if one program complains about a file,
that it can't find although it is in the current directory, prefix the
filename with @samp{./} ot @samp{.\}.

@unnumberedsec Dynamic Memory allocation for @TeX{}

The @TeX{} versions dated later than March 2nd, 1991 have a dynamic
memory allocation scheme for most of the large arrays. The startup
message reflects this (TeX Version 3.1t2var). There are certainly better
schemes, to achieve dynamic allocation, but I found, that the chosen
approach required only very minimal changes to the source files.

Originally the header file @file{texd.h} (part of the sources) contained
some defines for the values of @code{memmax}, @code{memtop},
@code{triesize} etc. I changed these defines into variables and also
changed the dependent array declarations into pointer declarations. Now,
before the main @TeX{} code gets control, these pointer are initialized
with malloced memory. Since I don't know, if there are any places in the
code, which assume that uninitialized memory is cleared, the flag, which
prevents TOS from clearing the whole TPA should not be set. This is to 
make really sure, that malloced memory is cleared. If you have a TOS
version earlier than 1.4, you don't have to bother with this, since
these version clear the whole memory with every program launch.@refill

To be able to modify the size of the arrays in the executables, I
borrowed the idea of the programs @file{fixstk.ttp} and
@file{printstk.ttp}, which come with the binary distribution of GNU-C
for the ST. These two programs allow the modification or the display of
the variable @code{stksize}, which determines, how the stack and the
memory is used by a program.@refill

@unnumberedsec @TeX{}-CONF.TTP

I therefore wrote a program called @file{tex-conf.ttp}, which allows the
modification and the display of @TeX{}'s main configuration values. This
works only if the executable is unstripped, because the information,
which is present in the symbol table is used to locate the variables in
the executable. Therefore you should never strip the @TeX{} or METAFONT
executables, or, if you do, then keep unstriped versions around.@refill

A sample output of @file{tex-conf.ttp} is shown in the following lines,
if it is invoked without any options (You also see the default
configuration for the files as they are in the archive).

@example
f:\tex >> tex-conf bigtex.ttp tex.ttp mf.ttp

TEX-CONF: The Configurator for TeX and METAFONT by fgth (Jul 18 1991)

bigtex.ttp: TEXT segment is 190556 (187K)
bigtex.ttp: DATA segment is 1084 (2K)
bigtex.ttp: BSS segment is 239258 (234K)

bigtex.ttp: bufsize is 3000 (3K)
bigtex.ttp: dvibufsize is 16384 (16K)
bigtex.ttp: fontmemsize is 50000 (196K)
bigtex.ttp: maxstrings is 7500 (30K)
bigtex.ttp: memmax is 131070 (512K)
bigtex.ttp: memtop is 131070 (0K)
bigtex.ttp: poolsize is 100000 (98K)
bigtex.ttp: savesize is 4000 (16K)
bigtex.ttp: stksize is 16384 (0K)
bigtex.ttp: triehash is 16000 (219K)
bigtex.ttp: triesize is 16000 (79K)

bigtex.ttp: approx. memory usage running as INITEX 1624562 (1587K)
bigtex.ttp: approx. memory usage running as VIRTEX 1400562 (1368K)

tex.ttp: TEXT segment is 197132 (193K)
tex.ttp: DATA segment is 1084 (2K)
tex.ttp: BSS segment is 69986 (69K)

tex.ttp: bufsize is 500 (1K)
tex.ttp: dvibufsize is 4096 (4K)
tex.ttp: fontmemsize is 30000 (118K)
tex.ttp: maxstrings is 5000 (20K)
tex.ttp: memmax is 50000 (196K)
tex.ttp: memtop is 50000 (0K)
tex.ttp: poolsize is 45000 (44K)
tex.ttp: savesize is 1000 (4K)
tex.ttp: stksize is 16384 (0K)
tex.ttp: triehash is 12000 (165K)
tex.ttp: triesize is 12000 (59K)

tex.ttp: approx. memory usage running as INITEX 889798 (869K)
tex.ttp: approx. memory usage running as VIRTEX 721798 (705K)

mf.ttp: TEXT segment is 198472 (194K)
mf.ttp: DATA segment is 1112 (2K)
mf.ttp: BSS segment is 121894 (120K)

mf.ttp: bufsize is 500 (1K)
mf.ttp: gfbufsize is 16384 (16K)
mf.ttp: maxstrings is 2000 (10K)
mf.ttp: memmax is 45000 (176K)
mf.ttp: memtop is 45000 (0K)
mf.ttp: poolsize is 32000 (32K)
mf.ttp: stksize is 16384 (0K)

mf.ttp: approx. memory usage for METAFONT 560362 (548K)
@end example

First of all, the program prints the sizes of the TEXT, DATA and BSS
segments of the executable. These values are found in the header of the
program file. Then the current values of some variables are printed. The
number of these variables differ depending on the file, which is
currently examined. Most of these variables define the size of a memory
array.

The variable @code{stksize} has the same meaning as in other GNU-C
produced executables. It determines the usage of stack and memory.
@samp{16k} means, that the executable will run on a 16 KB stack. This
size works okay for me, but if you experience strange effect (bombs)
while running @TeX{} you might increase the value. Previously I had set
@code{stksize} to @samp{-1L}, which would cause the program to grab
every bit of memory it could get and do mallocs from internal heap. But
that's not very nice in a multitasking environment (aka MiNT).@refill

The variable @code{memtop} doesn't actually define a memory array, but
it is presented, since it's value must be equal to @code{memmax}, when
the @file{tex.ttp} runs as INI@TeX{} (@code{-i} option). @code{memmax}
may be larger than @code{memtop} for normal operation, but both
(@code{memtop} and @code{memmax}) may not be larger than 65530 for a
normal sized @TeX{} or METAFONT and not larger than 262140 for a
Big@TeX{}. The variable @code{triehash} is for information purposes
only. The printed value is directly dependent on @code{triesize} and is
only used when the memory usage for INITEX is calculated. INITEX uses 6
additional arrays for the handling of hyphenation pattern, which are all
subsumed under the name @code{triehash}. The 6 additional arrays are
also the reason, why an INITEX with static arrays is so much bigger than
VIRTEX with the same sizes.@refill

The other values directly define the size on an array. The values in
braces show the actual memory, which is allocated for that array. The
last line, that is printed, is the calculated memory usage, which is
basically the sum of all shown arrays plus the TEXT-, DATA- and BSS
segments sizes.

@unnumberedsec Configuring @TeX{} and METAFONT

Now to change a value, you simple give the value name as an option
during program invocation. For example:

@example
tex-conf -bufsize 2000 h:\tex\initex.ttp h:\tex\virtex.ttp
@end example

or

@example
tex-conf -memtop 50000 -memmax 50000 h:\tex\initex.ttp \ 
    h:\tex\virtex.ttp
@end example

Changing a value makes it in most cases necessary to create new dumped
formats with @samp{tex -i} (*.FMT files).

I made all the above mentioned changes in the first place to get TeX
also running on a 1 meg ST. For a 1 meg ST you might modify
@code{dvibufsize}, @samp{memmax = memtop}, and @code{triesize}. I was
able to create *.FMT formats on a 1 meg ST (artificially achieved with a
1536 kb ram disk on my 2,5 meg ST) with @samp{memmax = memtop = 50000},
@samp{triesize = 12000} and @samp{dvibufsize = 4096}, but I must admit
there was nothing in memory except the hard disk driver and an
environment setting program. A @code{triesize} of 12000 is necessary
for german hyphenation pattern. If you only use English hyphenation
pattern you can decrease @code{triesize} to 8000. This in turn might
allow you to increase @samp{memmax = memtop} to maximum. Remember, the
main problem was initex with its 6 additional array for hyphenation
compared with virtex. The increase of @code{triesize} by 1000 costs
15000 bytes of memory.@refill

I've included the program @file{setenv.prg} and a file @file{env.inf} in
the @TeX{} executable archive. @samp{setenv.prg} is an environment
setter for the AES. @samp{setenv.prg} goes into the auto folder and
@samp{env.inf} into the root directory of your boot drive.
@samp{env.inf} is included as an example for a possible configuration.
I've included this program, to allow the invocation of @TeX{} from the
desktop.@refill

Concluding this section, here is a short recipe to produce
@file{plain.fmt} files on a 1 meg ST.

@itemize @bullet
@item 
check, that @samp{memmax = memtop = 50000}, @samp{triesize = 12000} and  
@samp{dvibufsize = 4096}. (This is done with @file{tex-conf.ttp} running
from a CLI) 

@item
edit @samp{env.inf} to reflect your current setting.

@item
copy @samp{env.prg} to the auto folder and @samp{env.inf} in root
directory of your boot drive.

@item
strip the auto folder to the bare minimum to get maximum memory
(only your hard disk driver and @samp{env.prg} should stay in place)

@item
reboot your ST to activate the new auto folder setting.

@item
invoke @samp{tex.ttp} from the desktop with the arguments 
@samp{plain \dump -i} or, if you start @file{tex.ttp} with only the
@samp{-i} option, type @samp{plain \dump}, when @TeX{} prompts with
@samp{**} (This creates the @file{plain.fmt} file) 

@item
repeat the above line if necessary for La@TeX{}.

@item
reboot the ST with your old configuration.

@item
Now you can now happily invoke @samp{tex.ttp} from a CLI and become a
@TeX{} wizard. 
@end itemize

@unnumberedsec WARNING

The complete port is sort of a quick and dirty port.  I'm quite happy
with the way it works, since I prefer a CLI environment like gulam. I'm
also not a @TeX{} or METAFONT wizard. I only compiled the sources. So,
if you experience problems or have questions, which concerns @TeX{}'s or
METAFONT's inner workings, DON'T write to me.  I won't be able to help
you. Instead post an article in the news group
@samp{comp.text.tex}.@refill

If you have Atari ST specific questions about this implementation,
you CAN write to me.

If you are interested, I can also send a file containing the diffs
relative to the files from Karl Berry (the original WEB2C kit), but I
won't send the complete WEB and WEB2C sources.

Additionally you will need the latest versions of the various @TeX{} and
Metafont macro packages like Plain, La@TeX{} etc. Good places to look for
these are the following archive sites:

@itemize @bullet
@item
[archive-server@@]sun.soe.clarkson.edu: Email and anon ftp

@item
[mail-server@@]cs.ruu.nl: Email and anon ftp (for European users)

@item 
labrea.stanford.edu: anon ftp (The official @TeX{} archive site)

@item
[mailserv@@]ymir.claremont.edu: Email and anon ftp

@item
[mailserv@@]rusmv1.rus.uni-stuttgart.de: Email and anon ftp (for
German users)
@end itemize

@unnumberedsec Unsorted List of Changes

The following is a list of differences between this @TeX{} and METAFONT
executables and the ones, which were available from the Atari archive at
terminator during the end of 1990 until the middle of Jan 1991.

@itemize @bullet
@item
Changed the path separator from @samp{:} to @samp{;}. This change allows
the use of standard TOS path names (ex. @samp{f:\tex}). Prior to this
you had to use the @samp{/dev/<partition>} notation for path names. All
the utility programs still use this notation, since I didn't rebuild
them with the modified support files in the common directory.

@item
Subdirectory search is enabled.

@item
Upon startup a message is printed, when the executable was compiled.

@item
Compiled with GNU-C v1.39 and maximum optimization (@code{-O},
@code{-fomit-frame-pointer}, @code{-fcombine-regs}. The additional flag
@code{-fstrength-reduce} caused errors in the DVI file.)

@item
Instead of ignoring all @samp{\r} characters in the input stream, only
the @samp{\r} from a @samp{\r\n} pair is removed.
@end itemize

Change to the version compiled later than March 2, 1991

@itemize @bullet
@item
Dynamic memory allocation for most of the internal arrays.

@item
Startup modified to reflect the dynamic allocation.
@end itemize

@unnumberedsec Contacting me

You can contact either by electronic or snail mail.

@example
Email:
ridderbusch.kd@@sni-usa.com	(America (North & South))
ridderbusch.kd@@sni.de		(Rest of World)

Snail:
Frank Ridderbusch
Sander Str. 17
W-4790 Paderborn
Germany
@end example

@bye
